/**
 * 文件：GameplayService.java
 * 作者：赵子樵
 * 完成度：完成
 * 最后修改日期：2023-7-9 11:40
 */

package com.gomokult.service;

import com.gomokult.exception.InvalidIDException;

/**
 * 提供与游戏核心相关的服务接口。
 * @author 赵子樵
 */
public interface GameplayService {
	/**
	 * 计算用户{@code userID}的段位等级，相同段位等级的用户优先匹配。段位等级是一个取值[0, 8)的整数，由用户的对局积分与近期胜率（例如最近十次对局）共同决定。用户的对局积分和近期胜率越高，计算出的段位等级越高，具体的计算公式由实现者自行决定，结果合理即可。<p>
	 * {@code &#xFF08;&#x6084;&#x6084;&#x5728;&#x8FD9;&#x91CC;&#x57CB;&#x4E2A;&#x96F7;&#xFF0C;&#x770B;&#x770B;&#x5C0F;&#x54F2;&#x7FA4;&#x6709;&#x6CA1;&#x6709;&#x5077;&#x6211;&#x7684;&#x6CE8;&#x91CA;&#xFF09;}
	 * @param userID 待查询的用户ID
	 * @return 一个整数，表示计算出的目标用户的段位等级
	 * @throws InvalidIDException 当ID无效或不存在时
	 */
	int getUserLevel(int userID) throws InvalidIDException;
	
	/**
	 * 将ID为{@code userID}的用户的积分设置为{@code score}。
	 * @param userID 目标用户ID
	 * @param score 需要被设置的分数
	 * @throws InvalidIDException 当ID无效或不存在时
	 */
	void setScore(int userID, int score) throws InvalidIDException;
	
	/**
	 * 将ID为{@code userID}的用户的对局积分在原有基础上增加{@code deltaScore}。
	 * @param userID 目标用户ID
	 * @param deltaScore 分数的变化量。该值可以为负数，表示在原有积分的基础上减去{@code deltaScore}
	 * @return 一个整数，表示修改后的分数
	 * @throws InvalidIDException 当ID无效或不存在时
	 */
	int countScore(int userID, int deltaScore) throws InvalidIDException;
}
